home *** CD-ROM | disk | FTP | other *** search
/ Delphi 2.0 - Programmer's Utilities Power Pack / Delphi 2.0 Programmer's Utilities Power Pack.iso / s_to_z / sortz10 / sortz.txt < prev    next >
Encoding:
Text File  |  1996-09-15  |  6.7 KB  |  167 lines
  1. Sortz VBX, Version 1.0
  2. Copyright (c) 1995, Martin Bryant, All Rights Reserved
  3.  
  4. Introduction
  5. ------------
  6. The SORTZ.VBX file is a custom control suitable for use with such
  7. programming languages as Visual Basic, Visual C++ and Delphi. It provides an
  8. efficient sort engine for numeric or string data stored in arrays of simple
  9. data types or user-defined types, and can work with 'huge' arrays (>64K).
  10.  
  11. Shareware Notice
  12. ----------------
  13. Sortz VBX is shareware. You are welcome to use it for a trial period but if
  14. you continue to use it then please register and support the shareware
  15. concept. You may freely copy/distribute the shareware version as long as you
  16. make no charge for it. If you register, then you may use it in commercial
  17. products with no royalty fee. Thank you for trying Sortz VBX!
  18. You can register by sending รบ10 sterling or equivalent foreign currency
  19. (cash preferred!) to Martin Bryant, 71 Hunstanton Drive, Brandlesholme,
  20. Bury, Lancashire BL8 1XH, England.
  21. Registered users receive free updates and a full list of our other products.
  22. Constructive comments/criticisms welcome at the above address or email
  23. martinbr@colossus.demon.co.uk
  24.  
  25. Compatibility
  26. -------------
  27. SORTZ.VBX is compatible with level 1 VBX controls.
  28.  
  29. Appearance
  30. ----------
  31. When added to a program the control appears in the toolbox as some sorted
  32. data. It is non-sizable on a form and is invisible at run-time.
  33.  
  34. Properties
  35. ----------
  36. In addition to the standard properties of Name, Index, Left and Top it also
  37. has the following custom properties...
  38.  
  39. About (read only)
  40. Gives version and copyright information.
  41.  
  42. Action (write-only/run-time only)
  43. Set to any value to initiate the sort.
  44. e.g. Sortz1.Action=0
  45.  
  46. ArrayPointer (write only/run-time only)
  47. Passes the base address of your array into the control using the Windows API
  48. Lstrcpy function. See the examples section later for exact details of how to
  49. do this.
  50. e.g. Sortz1.ArrayPointer = Lstrcpy(a(), a()) 'pass address of VB HAD
  51. or...Sort\1.ArrayPointer = Lstrcpy(a(1), a(1)) 'pass address of 1st element
  52.  
  53. ArrayPointerType
  54. The base address of your array can be passed in two ways. Firstly it can
  55. simply be a far pointer to the first element of the array. This works fine
  56. for single segment arrays (VB and Delphi arrays <64K) and huge memory object
  57. arrays (memory allocated by GlobalAllocPtr possibly >64K). Alternatively,
  58. because VB has its own internal format for 'huge' arrays, you can pass the
  59. address of the array descriptor (HAD) to the control. Either way, you must
  60. inform the control what type of pointer you are passing.
  61. e.g. Sortz1.ArrayPointerType = 1
  62.  
  63. ArraySize
  64. Defines the number of elements (NOT the number of bytes) in the array.
  65. e.g. Sortz1.ArraySize = UBound(a) - LBound(a) + 1
  66.  
  67. BeepOnError
  68. If the control detects any errors it will, by default, produce a 'beep'.
  69. This can be turned off by setting this property to false.
  70. e.g. Sortz1.BeepOnError = False
  71.  
  72. ElementSize
  73. Defines the number of bytes per array element.
  74. e.g. Sortz1.ElementSize = 2
  75. will define each element to have 2 bytes.
  76. Common VB data types have the following sizes:- Integer(2), Long(4),
  77. Single(4), Double(8), Currency(8), String(4), String*N(N). Arrays of
  78. user-defined types obviously have to have their size calculated manually and
  79. CAREFULLY to avoid internal errors.
  80.  
  81. Error (read-only/run-time only)
  82. May return an error number as follows...
  83. 0 - no error
  84. 1 - array address not specified (via ArrayPointer property)
  85. 2 - SortFieldSize too big (limited to 16384 bytes)
  86. 3 - SortFieldStartOffset/SortFieldSize/ElementSize value(s) invalid
  87. 4 - ElementSize cannot be less than SortFieldSize
  88. 5 - specified SortFieldDataType not supported in shareware version
  89.  
  90. SortFieldDataType
  91. An enumerated list allows you to tell the control what type of data the sort
  92. field contains.
  93. e.g. Sortz1.SortFieldDataType = 0
  94. defines the data type to be a signed integer.
  95. Note that the shareware version only supports integer fields e.g. Integer,
  96. Long and Currency (stored internally as an 8-byte signed integer). The
  97. registered version also supports all standard floating point formats and
  98. variable-/fixed-length strings.
  99. Note that the SortFieldSize property can be used to specify the length of
  100. integers and fixed-length strings.
  101.  
  102. SortFieldSize
  103. Defines the number of bytes the sort field occupies. If the array is of a
  104. simple type, then SortFieldSize will be equal to ElementSize. However in
  105. user-defined types the field to sort the array on, may be one of many, and
  106. hence SortFieldSize would usually be less than ElementSize.
  107. e.g. Sortz1.SortFieldSize = 2
  108. Common VB data types have the following sizes:- Integer(2), Long(4),
  109. Single(4), Double(8), Currency(8), String(4), String*N(N).
  110.  
  111. SortFieldStartOffset
  112. Defines the byte offset from the start of each array element at which the
  113. sort field begins. If the array is of a simple data type then
  114. SortFieldStartOffset will be zero. However in user-defined types you must
  115. calculate how many bytes into each element the sort field starts.
  116. e.g. Sortz1.SortFieldStartOffset = 4
  117.  
  118. SortOrder
  119. Select 0 for ascending sort, 1 for descending sort.
  120. e.g. Sortz1.SortOrder = 1
  121.  
  122. The default Name property prefix and class name is 'Sortz'.
  123.  
  124. Example
  125. -------
  126. The following code segment sorts an array of 100 integers.
  127.  
  128. Declare Function Lstrcpy Lib "kernel" (p1() As Any, p2() As Any) As Long
  129.  
  130. Dim a(1 To 100) As Integer
  131.  
  132. Dim i
  133.  
  134. For i = LBound(a) To UBound(a) 'initialise array to random values
  135.     a(i) = Rnd * 64000 - 32000
  136. Next
  137.  
  138. sortz1.ArraySize = UBound(a) - LBound(a) + 1 '100-1+1=100
  139. sortz1.ArrayPointerType = 1 'VB 'HAD' ('Handle to Array Descriptor')
  140. sortz1.ElementSize = 2 'VB 'Integer' occupies 2 bytes
  141. sortz1.SortFieldDataType = 0 'signed integer
  142. sortz1.SortFieldStartOffset = 0 'simple data type array
  143. sortz1.SortFieldSize = 2 'VB 'Integer' occupies 2 bytes
  144. sortz1.SortOrder = 0 'ascending order
  145. sortz1.ArrayPointer = Lstrcpy(a(), a()) 'pass address of 'HAD'
  146. sortz1.Action = 0 'do it!
  147.  
  148. Notes
  149. -----
  150. Sortz VBX can handle arrays of VB fixed length strings but you will have
  151. to modify the declaration of the Windows API Lstrcpy function as follows,
  152. as VB fixed length strings are NOT compatible with the 'Any' type!
  153. e.g. for 100 character strings
  154. Declare Function Lstrcpy Lib "kernel" (p1() As String * 100, p2() As String * 100) As Long
  155. Dim a(1 To 10) As String * 100
  156.  
  157. Delphi users should pass the address of the 1st element of the array to the
  158. control. (VB users can do this but only for single segment arrays. It is
  159. also slightly more efficient to use this method.)
  160.  
  161. Note that the control has a different SortFieldDataType for VB variable
  162. length strings when in a simple array and in a user-defined type.
  163.  
  164. Events
  165. ------
  166. The control has no pre-defined events.
  167.